[% page.title = 'API Method: reports create (matches)'
   page.tab = 'api'
%]

<h2>
  POST /:user_id/reports/:folder_id/matches/:matches_id
</h2>

<p>
Creates a reports folder in the specified user account and generates reports therein based on the specified matches folder.
Returns a representation of the created reports folder with a 201 Created HTTP status code.
</p>

<h3>URL:</h3>
<code>[% site.url %]/<em>user_id</em>/reports/<em>folder_id</em>/matches/<em>:matches_id</em>.<em>format</em></code>

<h3>Formats (<a href="formats">about return formats</a>):</h3>
<code>[% INCLUDE 'api/_formats.phtml' %]</code>

<h3>HTTP Methods (<a href="http-methods">about HTTP methods</a>):</h3>
<code>POST</code>

<h3>Requires Authentication (<a href="authentication">about authentication</a>):</h3>
<code>true</code>

<h3>Parameters:</h3>
<ul>
<li><code>folder_id</code>.  Required. The ID of the reports folder to create.</li>
<li><code>matches_id</code>.  Optional. The ID of the matches folder to create a report from.
Defaults to the same value as <code>folder_id</code>.
<ul>
<li>Example: <code>[% site.url %]/kdd09/reports/pc_papers/matches/pc_papers</code><br/>
<li>Or equivalently, <code>[% site.url %]/kdd09/reports/pc_papers/matches</code><br/>
</ul>
</li>
<li><code><em>description</em></code>.  Optional. The description of the folder to create.</li>
<li><code><em>mode</em></code>.  Optional. Whether the reports folder is publicly accessible or whether authentication is required to access. 
Values can be <code>public</code> or <code>private</code>. Folders are public by default if no mode is specified.</li>
<li><code><em>type</em></code>.  Optional. Report type. 
Values can be <code>html</code> or <code>graphviz</code>. The default value is <code>html</code>.</li>
</ul>

<h3>Usage Examples:</h3>
<blockquote>
<h4>cURL (<a href="curl">about cURL</a>):</h4>
<code>curl -X POST -H "Token:mytoken" -d "description=Matches between KDD 2009 PC and papers"<span class="cr"></span><br/>
[% site.url %]/kdd09/reports/pc_papers_matches/matches/pc_papers.xml</code><br/>
</blockquote>

<h3>Response (<a href="return-values">about return values</a>):</h3>
<blockquote>
<h4>XML example:</h4>
<pre>[% FILTER html -%]
<?xml version="1.0" encoding="UTF-8"?>
<result>
  <folder>
    <id>pc_papers_matches</id>
    <created>1293480802</created>
    <description>Matches between KDD09 PC and papers</description>
    <matches_id>pc_papers</matches_id>
    <mode>private</mode>
    <modified>1293480802</modified>
  </folder>
</result>
[% END %]</pre>
</blockquote>


